home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 July: Mac OS SDK / Dev.CD Jul 00 SDK2.toast / Development Kits / Hardware / PowerManager DDK 1.0f1 / Interfaces&Libraries / Interfaces / Multiprocessing.h < prev    next >
Encoding:
C/C++ Source or Header  |  1999-10-08  |  29.3 KB  |  969 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        Multiprocessing.h
  3.  
  4.      Contains:    Multiprocessing interfaces
  5.  
  6.      Version:    Multiprocessing API version 2.0, integrated nanokernel support
  7.  
  8.      DRI:        Alan Lillich
  9.  
  10.      Copyright:    © 1996-1999 by Apple Computer, Inc. and © 1995-1997 DayStar Digital, Inc.
  11.  
  12.      Warning:    *** APPLE INTERNAL USE ONLY ***
  13.                  This file may contain unreleased API's
  14.  
  15.      BuildInfo:    Built by:            Scott Johnson
  16.                  On:                    10/8/99 11:26 AM
  17.                  With Interfacer:    3.0d13   (MPW PowerPC)
  18.                  From:                Multiprocessing.i
  19.                      Revision:        64
  20.                      Dated:            8/12/99
  21.                      Last change by:    JM3
  22.                      Last comment:    [2362976]  Added cpuID field to the MPTaskInfo structure, and
  23.  
  24.      Bugs:        Report bugs to Radar component "System Interfaces", "Latest"
  25.                  List the version information (from above) in the Problem Description.
  26.  
  27. */
  28.  
  29. /*
  30.    ===========================================================================================
  31.    *** WARNING: You must properly check the availability of MP services before calling them!
  32.    See the section titled "Checking API Availability".
  33.    ===========================================================================================
  34. */
  35.  
  36.  
  37. #ifndef __MULTIPROCESSING__
  38. #define __MULTIPROCESSING__
  39.  
  40. #ifndef __MACTYPES__
  41. #include <MacTypes.h>
  42. #endif
  43.  
  44. #ifndef __CODEFRAGMENTS__
  45. #include <CodeFragments.h>
  46. #endif
  47.  
  48.  
  49. #ifndef __DRIVERSERVICES__
  50. #include <DriverServices.h>
  51. #endif
  52.  
  53.  
  54.  
  55.  
  56.  
  57. #if PRAGMA_ONCE
  58. #pragma once
  59. #endif
  60.  
  61. #ifdef __cplusplus
  62. extern "C" {
  63. #endif
  64.  
  65. #if PRAGMA_IMPORT
  66. #pragma import on
  67. #endif
  68.  
  69. #if PRAGMA_STRUCT_ALIGN
  70.     #pragma options align=power
  71. #elif PRAGMA_STRUCT_PACKPUSH
  72.     #pragma pack(push, 2)
  73. #elif PRAGMA_STRUCT_PACK
  74.     #pragma pack(2)
  75. #endif
  76.  
  77. /*
  78.    ===========================================================================================
  79.    This is the header file for version 2.0 of the Mac OS multiprocessing support.  This version
  80.    has been totally reimplemented and has significant new services.  The main goal of the
  81.    reimplementation has been to transfer task management into the core operating system to provide
  82.    much more reliable and more efficient operation, including on single processor machines.
  83.    The memory management has also been massively improved, it is much faster and wastes much
  84.    less space.  New services include POSIX style per-task storage, timers with millisecond and
  85.    microsecond resolutions, memory allocation at a specified alignment, and system pageable
  86.    and RAM resident memory pools.  See the MP API documentation for details.
  87.    The old "DayStar" debugging services (whose names began with an underscore) have been
  88.    removed from this header.  A very few are still implemented for binary compatibility, or in
  89.    cases where they happened to be exposed inappropriately.  (E.g. _MPIsFullyInitialized must
  90.    be called to see if the MP API is ReallyTruly™ usable.)  New code and recompiles of old
  91.    code should avoid use of these defunct services, except for _MPIsFullyInitialized.
  92.    ===========================================================================================
  93. */
  94.  
  95.  
  96. /*
  97.    ===========================================================================================
  98.    The following services are from the original MP API and remain supported in version 2.0:
  99.       MPProcessors
  100.       MPCreateTask
  101.       MPTerminateTask
  102.       MPCurrentTaskID
  103.       MPYield
  104.       MPExit
  105.       MPCreateQueue
  106.       MPDeleteQueue
  107.       MPNotifyQueue
  108.       MPWaitOnQueue
  109.       MPCreateSemaphore
  110.       MPCreateBinarySemaphore        (In C only, a macro that calls MPCreateSemaphore.)
  111.       MPDeleteSemaphore
  112.       MPSignalSemaphore
  113.       MPWaitOnSemaphore
  114.       MPCreateCriticalRegion
  115.       MPDeleteCriticalRegion
  116.       MPEnterCriticalRegion
  117.       MPExitCriticalRegion
  118.       MPAllocate                    (Deprecated, use MPAllocateAligned for new builds.)
  119.       MPFree
  120.       MPBlockCopy
  121.       MPLibraryIsLoaded            (In C only, a macro.)
  122.       _MPIsFullyInitialized        (See comments about checking for MP API availability.)
  123.    ===========================================================================================
  124. */
  125.  
  126.  
  127. /*
  128.    ===========================================================================================
  129.    The following services are new in version 2.0:
  130.       MPProcessorsScheduled
  131.       MPSetTaskWeight
  132.       MPTaskIsPreemptive
  133.       MPAllocateTaskStorageIndex
  134.       MPDeallocateTaskStorageIndex
  135.       MPSetTaskStorageValue
  136.       MPGetTaskStorageValue
  137.       MPSetQueueReserve
  138.       MPCreateEvent
  139.       MPDeleteEvent
  140.       MPSetEvent
  141.       MPWaitForEvent
  142.       UpTime
  143.       DurationToAbsolute
  144.       AbsoluteToDuration
  145.       MPDelayUntil
  146.       MPCreateTimer
  147.       MPDeleteTimer
  148.       MPSetTimerNotify
  149.       MPArmTimer
  150.       MPCancelTimer
  151.       MPSetExceptionHandler
  152.       MPThrowException
  153.       MPDisposeTaskException
  154.       MPExtractTaskState
  155.       MPSetTaskState
  156.       MPRegisterDebugger
  157.       MPUnregisterDebugger
  158.       MPAllocateAligned            (Preferred over MPAllocate.)
  159.       MPGetAllocatedBlockSize
  160.       MPBlockClear
  161.       MPDataToCode
  162.       MPRemoteCall                (Preferred over _MPRPC.)
  163.    ===========================================================================================
  164. */
  165.  
  166.  
  167. /*
  168.    ===========================================================================================
  169.    The following services are new in version 2.1:
  170.       MPCreateNotification
  171.       MPDeleteNotification
  172.       MPModifyNotification
  173.       MPCauseNotification
  174.       MPGetNextTaskID
  175.       MPGetNextCpuID
  176.    ===========================================================================================
  177. */
  178.  
  179.  
  180. /*
  181.    ===========================================================================================
  182.    The following services are "unofficial" extensions to the original API.  They are not in
  183.    the multiprocessing API documentation, but were in previous versions of this header.  They
  184.    remain supported in version 2.0.  They may not be supported in other environments.
  185.       _MPRPC                        (Deprecated, use MPRemoteCall for new builds.)
  186.       _MPAllocateSys                (Deprecated, use MPAllocateAligned for new builds.)
  187.       _MPTaskIsToolboxSafe
  188.       _MPLibraryVersion
  189.       _MPLibraryIsCompatible
  190.    ===========================================================================================
  191. */
  192.  
  193.  
  194. /*
  195.    ===========================================================================================
  196.    The following services were in previous versions of this header for "debugging only" use.
  197.    They are NOT implemented in version 2.0.  For old builds they can be accessed by defining
  198.    the symbol MPIncludeDefunctServices to have a nonzero value.
  199.       _MPInitializePrintf
  200.       _MPPrintf
  201.       _MPDebugStr
  202.       _MPStatusPString
  203.       _MPStatusCString
  204.    ===========================================================================================
  205. */
  206.  
  207.  
  208. /*
  209.    §
  210.    ===========================================================================================
  211.    General Types and Constants
  212.    ===========================
  213. */
  214.  
  215.  
  216. #define MPCopyrightNotice    \
  217.     "Copyright © 1995-1999 Apple Computer, Inc.\n"
  218. #define MPLibraryName "MPLibrary"
  219. #define MPLibraryCName MPLibraryName
  220. #define MPLibraryPName "\p" MPLibraryName
  221. #define MP_API_Version "2.0"
  222.  
  223. enum {
  224.     MPLibrary_MajorVersion        = 2,
  225.     MPLibrary_MinorVersion        = 0,
  226.     MPLibrary_Release            = 1,
  227.     MPLibrary_DevelopmentRevision = 1
  228. };
  229.  
  230.  
  231. typedef CFragContextID                     MPProcessID;
  232. typedef struct OpaqueMPTaskID*             MPTaskID;
  233. typedef struct OpaqueMPQueueID*         MPQueueID;
  234. typedef struct OpaqueMPSemaphoreID*     MPSemaphoreID;
  235. typedef struct OpaqueMPCriticalRegionID*  MPCriticalRegionID;
  236. typedef struct OpaqueMPTimerID*         MPTimerID;
  237. typedef struct OpaqueMPEventID*         MPEventID;
  238. typedef struct OpaqueMPAddressSpaceID*     MPAddressSpaceID;
  239. typedef struct OpaqueMPNotificationID*     MPNotificationID;
  240. typedef struct OpaqueMPCoherenceID*     MPCoherenceID;
  241. typedef struct OpaqueMPCpuID*             MPCpuID;
  242. typedef struct OpaqueMPOpaqueID*         MPOpaqueID;
  243. enum {
  244.     kMPNoID                        = kInvalidID                    /* New code should use kInvalidID everywhere.*/
  245. };
  246.  
  247.  
  248. typedef OptionBits                         MPTaskOptions;
  249. typedef UInt32                             TaskStorageIndex;
  250. typedef UInt32                             TaskStorageValue;
  251. typedef ItemCount                         MPSemaphoreCount;
  252. typedef UInt32                             MPTaskWeight;
  253. typedef UInt32                             MPEventFlags;
  254. typedef UInt32                             MPExceptionKind;
  255. typedef UInt32                             MPTaskStateKind;
  256. typedef UInt32                             MPDebuggerLevel;
  257. enum {
  258.     kDurationImmediate            = 0L,
  259.     kDurationForever            = 0x7FFFFFFF,
  260.     kDurationMillisecond        = 1,
  261.     kDurationMicrosecond        = -1
  262. };
  263.  
  264.  
  265. /*
  266.    §
  267.    ===========================================================================================
  268.    Tasking Services
  269.    ================
  270. */
  271.  
  272.  
  273. EXTERN_API_C( ItemCount )
  274. MPProcessors                    (void);
  275.  
  276. /* The physical total.*/
  277. EXTERN_API_C( ItemCount )
  278. MPProcessorsScheduled            (void);
  279.  
  280. /* Those currently in use.*/
  281. EXTERN_API_C( OSStatus )
  282. MPGetNextCpuID                    (MPCoherenceID             owningCoherenceID,
  283.                                  MPCpuID *                cpuID);
  284.  
  285.  
  286. enum {
  287.                                                                 /* For MPCreateTask options*/
  288.     kMPCreateTaskSuspendedMask    = 1L << 0,
  289.     kMPCreateTaskTakesAllExceptionsMask = 1L << 1,
  290.     kMPCreateTaskValidOptionsMask = kMPCreateTaskSuspendedMask | kMPCreateTaskTakesAllExceptionsMask
  291. };
  292.  
  293. /* -------------------------------------------------------------------------------------------*/
  294.  
  295.  
  296. typedef CALLBACK_API_C( OSStatus , TaskProc )(void *parameter);
  297. EXTERN_API_C( OSStatus )
  298. MPCreateTask                    (TaskProc                 entryPoint,
  299.                                  void *                    parameter,
  300.                                  ByteCount                 stackSize,
  301.                                  MPQueueID                 notifyQueue,
  302.                                  void *                    terminationParameter1,
  303.                                  void *                    terminationParameter2,
  304.                                  MPTaskOptions             options,
  305.                                  MPTaskID *                task);
  306.  
  307. EXTERN_API_C( OSStatus )
  308. MPTerminateTask                    (MPTaskID                 task,
  309.                                  OSStatus                 terminationStatus);
  310.  
  311. EXTERN_API_C( OSStatus )
  312. MPSetTaskWeight                    (MPTaskID                 task,
  313.                                  MPTaskWeight             weight);
  314.  
  315. EXTERN_API_C( Boolean )
  316. MPTaskIsPreemptive                (MPTaskID                 taskID);
  317.  
  318. /* May be kInvalidID.*/
  319. EXTERN_API_C( void )
  320. MPExit                            (OSStatus                 status);
  321.  
  322. EXTERN_API_C( void )
  323. MPYield                            (void);
  324.  
  325. EXTERN_API_C( MPTaskID )
  326. MPCurrentTaskID                    (void);
  327.  
  328. EXTERN_API_C( OSStatus )
  329. MPGetNextTaskID                    (MPProcessID             owningProcessID,
  330.                                  MPTaskID *                taskID);
  331.  
  332.  
  333. /* -------------------------------------------------------------------------------------------*/
  334.  
  335.  
  336. /*
  337.    ---------------------------------------------------
  338.    ! The task storage services are new in version 2.0.
  339. */
  340.  
  341.  
  342. EXTERN_API_C( OSStatus )
  343. MPAllocateTaskStorageIndex        (TaskStorageIndex *        index);
  344.  
  345. EXTERN_API_C( OSStatus )
  346. MPDeallocateTaskStorageIndex    (TaskStorageIndex         index);
  347.  
  348. EXTERN_API_C( OSStatus )
  349. MPSetTaskStorageValue            (TaskStorageIndex         index,
  350.                                  TaskStorageValue         value);
  351.  
  352. EXTERN_API_C( TaskStorageValue )
  353. MPGetTaskStorageValue            (TaskStorageIndex         index);
  354.  
  355.  
  356. /*
  357.    §
  358.    ===========================================================================================
  359.    Synchronization Services
  360.    ========================
  361. */
  362.  
  363.  
  364. EXTERN_API_C( OSStatus )
  365. MPCreateQueue                    (MPQueueID *            queue);
  366.  
  367. EXTERN_API_C( OSStatus )
  368. MPDeleteQueue                    (MPQueueID                 queue);
  369.  
  370. EXTERN_API_C( OSStatus )
  371. MPNotifyQueue                    (MPQueueID                 queue,
  372.                                  void *                    param1,
  373.                                  void *                    param2,
  374.                                  void *                    param3);
  375.  
  376. EXTERN_API_C( OSStatus )
  377. MPWaitOnQueue                    (MPQueueID                 queue,
  378.                                  void **                param1,
  379.                                  void **                param2,
  380.                                  void **                param3,
  381.                                  Duration                 timeout);
  382.  
  383. EXTERN_API_C( OSStatus )
  384. MPSetQueueReserve                (MPQueueID                 queue,
  385.                                  ItemCount                 count);
  386.  
  387.  
  388. /* -------------------------------------------------------------------------------------------*/
  389.  
  390.  
  391. EXTERN_API_C( OSStatus )
  392. MPCreateSemaphore                (MPSemaphoreCount         maximumValue,
  393.                                  MPSemaphoreCount         initialValue,
  394.                                  MPSemaphoreID *        semaphore);
  395.  
  396. EXTERN_API_C( OSStatus )
  397. MPDeleteSemaphore                (MPSemaphoreID             semaphore);
  398.  
  399. EXTERN_API_C( OSStatus )
  400. MPSignalSemaphore                (MPSemaphoreID             semaphore);
  401.  
  402. EXTERN_API_C( OSStatus )
  403. MPWaitOnSemaphore                (MPSemaphoreID             semaphore,
  404.                                  Duration                 timeout);
  405.  
  406.  
  407. #define MPCreateBinarySemaphore(semaphore)    \
  408.             MPCreateSemaphore ( 1, 1, (semaphore) )
  409.  
  410. /* -------------------------------------------------------------------------------------------*/
  411.  
  412.  
  413. EXTERN_API_C( OSStatus )
  414. MPCreateCriticalRegion            (MPCriticalRegionID *    criticalRegion);
  415.  
  416. EXTERN_API_C( OSStatus )
  417. MPDeleteCriticalRegion            (MPCriticalRegionID     criticalRegion);
  418.  
  419. EXTERN_API_C( OSStatus )
  420. MPEnterCriticalRegion            (MPCriticalRegionID     criticalRegion,
  421.                                  Duration                 timeout);
  422.  
  423. EXTERN_API_C( OSStatus )
  424. MPExitCriticalRegion            (MPCriticalRegionID     criticalRegion);
  425.  
  426.  
  427. /* -------------------------------------------------------------------------------------------*/
  428.  
  429. EXTERN_API( OSStatus )
  430. MPCreateEvent                    (MPEventID *            event)                                THREEWORDINLINE(0x3F3C, 0x0016, 0xAA7F);
  431.  
  432. EXTERN_API_C( OSStatus )
  433. MPDeleteEvent                    (MPEventID                 event);
  434.  
  435. EXTERN_API_C( OSStatus )
  436. MPSetEvent                        (MPEventID                 event,
  437.                                  MPEventFlags             flags);
  438.  
  439. EXTERN_API( OSStatus )
  440. MPWaitForEvent                    (MPEventID                 event,
  441.                                  MPEventFlags *            flags,
  442.                                  Duration                 timeout)                            THREEWORDINLINE(0x3F3C, 0x0019, 0xAA7F);
  443.  
  444. /*
  445.    §
  446.    ===========================================================================================
  447.    Notification Services (API)
  448.    =====================
  449. */
  450.  
  451.  
  452. EXTERN_API_C( OSStatus )
  453. MPCreateNotification            (MPNotificationID *        notificationID);
  454.  
  455. /* -------------------------------------------------------------------------------------------*/
  456.  
  457. EXTERN_API_C( OSStatus )
  458. MPDeleteNotification            (MPNotificationID         notificationID);
  459.  
  460. /* -------------------------------------------------------------------------------------------*/
  461.  
  462. EXTERN_API_C( OSStatus )
  463. MPModifyNotification            (MPNotificationID         notificationID,
  464.                                  MPOpaqueID             anID,
  465.                                  void *                    notifyParam1,
  466.                                  void *                    notifyParam2,
  467.                                  void *                    notifyParam3);
  468.  
  469. /* -------------------------------------------------------------------------------------------*/
  470.  
  471. EXTERN_API_C( OSStatus )
  472. MPCauseNotification                (MPNotificationID         notificationID);
  473.  
  474. /*
  475.    §
  476.    ===========================================================================================
  477.    Timer Services
  478.    ==============
  479. */
  480.  
  481.  
  482. /*
  483.    --------------------------------------------
  484.    ! The timer services are new in version 2.0.
  485. */
  486.  
  487.  
  488. #if 0
  489. /* For now these are taken from DriverServices, should be in a better place.*/
  490. EXTERN_API_C( AbsoluteTime )
  491. UpTime                            (void);
  492.  
  493. EXTERN_API_C( AbsoluteTime )
  494. DurationToAbsolute                (Duration                 duration);
  495.  
  496. EXTERN_API_C( Duration )
  497. AbsoluteToDuration                (AbsoluteTime             time);
  498.  
  499. #endif  /* 0 */
  500.  
  501. enum {
  502.                                                                 /* For MPArmTimer options*/
  503.     kMPPreserveTimerIDMask        = 1L << 0,
  504.     kMPTimeIsDeltaMask            = 1L << 1,
  505.     kMPTimeIsDurationMask        = 1L << 2
  506. };
  507.  
  508.  
  509. EXTERN_API_C( OSStatus )
  510. MPDelayUntil                    (AbsoluteTime *            expirationTime);
  511.  
  512. EXTERN_API_C( OSStatus )
  513. MPCreateTimer                    (MPTimerID *            timerID);
  514.  
  515. EXTERN_API_C( OSStatus )
  516. MPDeleteTimer                    (MPTimerID                 timerID);
  517.  
  518. EXTERN_API_C( OSStatus )
  519. MPSetTimerNotify                (MPTimerID                 timerID,
  520.                                  MPOpaqueID             anID,
  521.                                  void *                    notifyParam1,
  522.                                  void *                    notifyParam2,
  523.                                  void *                    notifyParam3);
  524.  
  525. EXTERN_API_C( OSStatus )
  526. MPArmTimer                        (MPTimerID                 timerID,
  527.                                  AbsoluteTime *            expirationTime,
  528.                                  OptionBits             options);
  529.  
  530. EXTERN_API_C( OSStatus )
  531. MPCancelTimer                    (MPTimerID                 timerID,
  532.                                  AbsoluteTime *            timeRemaining);
  533.  
  534.  
  535. /*
  536.    §
  537.    ===========================================================================================
  538.    Memory Services
  539.    ===============
  540. */
  541.  
  542.  
  543. enum {
  544.                                                                 /* Maximum allocation request size is 1GB.*/
  545.     kMPMaxAllocSize                = 1024L * 1024 * 1024
  546. };
  547.  
  548. enum {
  549.                                                                 /* Values for the alignment parameter to MPAllocateAligned.*/
  550.     kMPAllocateDefaultAligned    = 0,
  551.     kMPAllocate8ByteAligned        = 3,
  552.     kMPAllocate16ByteAligned    = 4,
  553.     kMPAllocate32ByteAligned    = 5,
  554.     kMPAllocate1024ByteAligned    = 10,
  555.     kMPAllocate4096ByteAligned    = 12,
  556.     kMPAllocateMaxAlignment        = 16,                            /* Somewhat arbitrary limit on expectations.*/
  557.     kMPAllocateAltiVecAligned    = kMPAllocate16ByteAligned,        /* The P.C. name.*/
  558.     kMPAllocateVMXAligned        = kMPAllocateAltiVecAligned,    /* The older, common name.*/
  559.     kMPAllocateVMPageAligned    = 254,                            /* Pseudo value, converted at runtime.*/
  560.     kMPAllocateInterlockAligned    = 255                            /* Pseudo value, converted at runtime.*/
  561. };
  562.  
  563. enum {
  564.                                                                 /* Values for the options parameter to MPAllocateAligned.*/
  565.     kMPAllocateClearMask        = 0x0001,                        /* Zero the allocated block.*/
  566.     kMPAllocateGloballyMask        = 0x0002,                        /* Allocate from the globally visible pool.*/
  567.     kMPAllocateResidentMask        = 0x0004,                        /* Allocate from the RAM-resident pool.*/
  568.     kMPAllocateNoGrowthMask        = 0x0010                        /* Do not attempt to grow the pool.*/
  569. };
  570.  
  571.  
  572. /* -------------------------------------------------------------------------------------------*/
  573.  
  574.  
  575. EXTERN_API_C( LogicalAddress )
  576. MPAllocateAligned                (ByteCount                 size,
  577.                                  UInt8                     alignment,
  578.                                  OptionBits             options);
  579.  
  580. /* ! MPAllocateAligned is new in version 2.0.*/
  581. EXTERN_API_C( LogicalAddress )
  582. MPAllocate                        (ByteCount                 size);
  583.  
  584. /* Use MPAllocateAligned instead.*/
  585. EXTERN_API_C( void )
  586. MPFree                            (LogicalAddress         object);
  587.  
  588. EXTERN_API_C( ByteCount )
  589. MPGetAllocatedBlockSize            (LogicalAddress         object);
  590.  
  591. /* -------------------------------------------------------------------------------------------*/
  592.  
  593.  
  594. EXTERN_API_C( void )
  595. MPBlockCopy                        (LogicalAddress         source,
  596.                                  LogicalAddress         destination,
  597.                                  ByteCount                 size);
  598.  
  599. EXTERN_API_C( void )
  600. MPBlockClear                    (LogicalAddress         address,
  601.                                  ByteCount                 size);
  602.  
  603. /* ! MPBlockClear is new in version 2.0.*/
  604. EXTERN_API_C( void )
  605. MPDataToCode                    (LogicalAddress         address,
  606.                                  ByteCount                 size);
  607.  
  608. /* ! MPDataToCode is new in version 2.0.*/
  609. /*
  610.    §
  611.    ===========================================================================================
  612.    Exception/Debugging Services
  613.    ============================
  614. */
  615.  
  616.  
  617. /*
  618.    -------------------------------------------------------------------------------------------
  619.    *** Important Note ***
  620.    ----------------------
  621.    
  622.    The functions MPExtractTaskState and MPSetTaskState infer the size of the "info" buffer
  623.    from the "kind" parameter.  A given value for MPTaskStateKind will always refer to a
  624.    single specific physical buffer layout.  Should new register sets be added, or the size
  625.    or number of any registers change, new values of MPTaskStateKind will be introduced to
  626.    refer to the new buffer layouts.
  627.    
  628.    The following types for the buffers are in MachineExceptions. The correspondence between
  629.    MPTaskStateKind values and MachineExceptions types is:
  630.    
  631.           kMPTaskStateRegisters                -> RegisterInformation
  632.           kMPTaskStateFPU                        -> FPUInformation
  633.           kMPTaskStateVectors                    -> VectorInformation
  634.           kMPTaskStateMachine                    -> MachineInformation
  635.           kMPTaskState32BitMemoryException    -> ExceptionInfo for old-style 32-bit memory exceptions
  636.    
  637.       For reference, on PowerPC the MachineExceptions types contain:
  638.    
  639.           RegisterInformation    -> The GPRs, 32 values of 64 bits each.
  640.           FPUInformation        -> The FPRs plus FPSCR, 32 values of 64 bits each, one value of
  641.                                   32 bits.
  642.           VectorInformation    -> The AltiVec vector registers plus VSCR and VRSave, 32 values
  643.                                   of 128 bits each, one value of 128 bits, and one 32 bit value.
  644.           MachineInformation    -> The CTR, LR, PC, each of 64 bits.  The CR, XER, MSR, MQ,
  645.                                   exception kind, and DSISR, each of 32 bits.  The 64 bit DAR.
  646.           ExceptionInfo        -> Only memory exceptions are specified, 4 fields of 32 bits each.
  647.                                   Note that this type only covers memory exceptions on 32-bit CPUs!
  648. */
  649. /*
  650.    The following types are declared here:
  651.           kMPTaskStateTaskInfo                -> MPTaskInfo
  652. */
  653. enum {
  654.                                                                 /* Values for the TaskStateKind to MPExtractTaskState and MPSetTaskState.*/
  655.     kMPTaskStateRegisters        = 0,                            /* The task general registers.*/
  656.     kMPTaskStateFPU                = 1,                            /* The task floating point registers*/
  657.     kMPTaskStateVectors            = 2,                            /* The task vector registers*/
  658.     kMPTaskStateMachine            = 3,                            /* The task machine registers*/
  659.     kMPTaskState32BitMemoryException = 4                        /* The task memory exception information for 32-bit CPUs.*/
  660. };
  661.  
  662. enum {
  663.     kMPTaskStateTaskInfo        = 5                                /* Static and dynamic information about the task.*/
  664. };
  665.  
  666. enum {
  667.                                                                 /* Option bits and numbers for MPDisposeTaskException.*/
  668.     kMPTaskPropagate            = 0,                            /* The exception is propagated.*/
  669.     kMPTaskResumeStep            = 1,                            /* The task is resumed and single step is enabled.*/
  670.     kMPTaskResumeBranch            = 2,                            /* The task is resumed and branch stepping is enabled.*/
  671.     kMPTaskResumeMask            = 0x0000,                        /* The task is resumed.*/
  672.     kMPTaskPropagateMask        = 1 << kMPTaskPropagate,        /* The exception is propagated.*/
  673.     kMPTaskResumeStepMask        = 1 << kMPTaskResumeStep,        /* The task is resumed and single step is enabled.*/
  674.     kMPTaskResumeBranchMask        = 1 << kMPTaskResumeBranch        /* The task is resumed and branch stepping is enabled.*/
  675. };
  676.  
  677. enum {
  678.                                                                 /* For kMPTaskStateTaskInfo, the task's runState*/
  679.     kMPTaskBlocked                = 0,                            /* Task is blocked (queued on resource)*/
  680.     kMPTaskReady                = 1,                            /* Task is runnable*/
  681.     kMPTaskRunning                = 2                                /* Task is running*/
  682. };
  683.  
  684. enum {
  685.                                                                 /* For kMPTaskStateTaskInfo, the version of the MPTaskInfo structure requested.*/
  686.     kMPTaskInfoVersion            = 2
  687. };
  688.  
  689.  
  690.  
  691. struct MPTaskInfo {
  692.     PBVersion                         version;                    /* Version of the data structure requested*/
  693.  
  694.     OSType                             name;                        /* Task name*/
  695.  
  696.     OSType                             queueName;                    /* Task's queue owner name*/
  697.     UInt16                             runState;                    /* Running, ready, blocked*/
  698.     UInt16                             lastCPU;                    /* Address of CPU where task previously ran*/
  699.     UInt32                             weight;                        /* Processing weight: 1 - 10,000*/
  700.  
  701.     MPProcessID                     processID;                    /* Owning process ID*/
  702.  
  703.     AbsoluteTime                     cpuTime;                    /* Accumulated task time*/
  704.     AbsoluteTime                     schedTime;                    /* Time when last scheduled*/
  705.     AbsoluteTime                     creationTime;                /* Time when task created*/
  706.  
  707.     ItemCount                         codePageFaults;                /* Page faults from code execution*/
  708.     ItemCount                         dataPageFaults;                /* Page faults from data access*/
  709.     ItemCount                         preemptions;                /* Number of times task was preempted*/
  710.  
  711.     MPCpuID                         cpuID;                        /* ID of CPU where task previously ran*/
  712. };
  713. typedef struct MPTaskInfo                MPTaskInfo;
  714. /*
  715.       Upon a task exception, the following message is sent to the designated queue:
  716.       1. The MPTaskID, 
  717.       2. The exception kind. These are enumerated in the interfaces header MachineExceptions.h 
  718.       3. N/A
  719. */
  720.  
  721.  
  722. /* -------------------------------------------------------------------------------------------*/
  723.  
  724. EXTERN_API_C( OSStatus )
  725. MPSetExceptionHandler            (MPTaskID                 task,
  726.                                  MPQueueID                 exceptionQ);
  727.  
  728. EXTERN_API_C( OSStatus )
  729. MPDisposeTaskException            (MPTaskID                 task,
  730.                                  OptionBits             action);
  731.  
  732. EXTERN_API_C( OSStatus )
  733. MPExtractTaskState                (MPTaskID                 task,
  734.                                  MPTaskStateKind         kind,
  735.                                  void *                    info);
  736.  
  737. EXTERN_API_C( OSStatus )
  738. MPSetTaskState                    (MPTaskID                 task,
  739.                                  MPTaskStateKind         kind,
  740.                                  void *                    info);
  741.  
  742. EXTERN_API_C( OSStatus )
  743. MPThrowException                (MPTaskID                 task,
  744.                                  MPExceptionKind         kind);
  745.  
  746. /* -------------------------------------------------------------------------------------------*/
  747.  
  748. EXTERN_API_C( OSStatus )
  749. MPRegisterDebugger                (MPQueueID                 queue,
  750.                                  MPDebuggerLevel         level);
  751.  
  752. EXTERN_API_C( OSStatus )
  753. MPUnregisterDebugger            (MPQueueID                 queue);
  754.  
  755.  
  756.  
  757. /*
  758.    §
  759.    ===========================================================================================
  760.    Remote Call Services
  761.    ====================
  762. */
  763.  
  764. typedef CALLBACK_API_C( void *, MPRemoteProcedure )(void *parameter);
  765.  
  766. typedef UInt8                             MPRemoteContext;
  767. enum {
  768.     kMPAnyRemoteContext            = 0,
  769.     kMPOwningProcessRemoteContext = 1
  770. };
  771.  
  772.  
  773. EXTERN_API_C( void *)
  774. MPRemoteCall                    (MPRemoteProcedure         remoteProc,
  775.                                  void *                    parameter,
  776.                                  MPRemoteContext         context);
  777.  
  778. /* ! MPRemoteCall is new in version 2.0.*/
  779. /*
  780.    §
  781.    ===========================================================================================
  782.    Checking API Availability
  783.    =========================
  784. */
  785.  
  786.  
  787. /*
  788.    ===========================================================================================
  789.    *** WARNING: You must properly check the availability of MP services before calling them!
  790.    ===========================================================================================
  791.    
  792.    Checking for the availability of the MP API is rather ugly.  This is a historical problem,
  793.    caused by the original implementation letting itself get prepared when it really wasn't
  794.    usable and complicated by some important clients then depending on weak linking to "work".
  795.    (And further complicated by CFM not supporting "deferred" imports, which is how many
  796.    programmers think weak imports work.)
  797.    
  798.    The end result is that the MP API library may get prepared by CFM but be totally unusable.
  799.    This means that if you import from the MP API library, you cannot simply check for a
  800.    resolved import to decide if MP services are available.  Worse, if you explicitly prepare
  801.    the MP API library you cannot assume that a noErr result from GetSharedLibrary means that
  802.    MP services are available.
  803.    
  804.    • If you import from the MP API library you MUST:
  805.    
  806.           Use the MPLibraryIsLoaded macro (or equivalent code in languages other than C) to tell
  807.           if the MP API services are available.  It is not sufficient to simply check that an
  808.           imported symbol is resolved as is commonly done for other libraries.  The macro expands
  809.           to the expression:
  810.    
  811.               ( ( (UInt32)_MPIsFullyInitialized != (UInt32)kUnresolvedCFragSymbolAddress ) &&
  812.                 ( _MPIsFullyInitialized () ) )
  813.    
  814.           This checks if the imported symbol _MPIsFullyInitialized is resolved and if resolved
  815.           calls it.  Both parts must succeed for the MP API services to be available.
  816.    
  817.    • If you explicitly prepare the MP API library you MUST:
  818.    
  819.           Use code similar to the following example to tell if the MP API services are available.
  820.           It is not sufficient to depend on just a noErr result from GetSharedLibrary.
  821.    
  822.               OSErr                        err;
  823.               Boolean                        mpIsAvailable            = false;
  824.               CFragConnectionID            connID                    = kInvalidID;
  825.               MPIsFullyInitializedProc    mpIsFullyInitialized    = NULL;
  826.    
  827.               err    = GetSharedLibrary    ( "\pMPLibrary", kCompiledCFragArch, kReferenceCFrag,
  828.                                         &connID, NULL, NULL );
  829.    
  830.               if ( err == noErr ) {
  831.                   err    = FindSymbol    ( connID, "\p_MPIsFullyInitialized",
  832.                                         (Ptr *) &mpIsFullyInitialized, NULL );
  833.               }
  834.    
  835.               if ( err == noErr ) {
  836.                   mpIsAvailable = (* mpIsFullyInitialized) ();
  837.               }
  838.    
  839.    ===========================================================================================
  840. */
  841.  
  842.  
  843. EXTERN_API_C( Boolean )
  844. _MPIsFullyInitialized            (void);
  845.  
  846. typedef CALLBACK_API_C( Boolean , MPIsFullyInitializedProc )(void );
  847. #define MPLibraryIsLoaded()        \
  848.             ( ( (UInt32)_MPIsFullyInitialized != (UInt32)kUnresolvedCFragSymbolAddress ) &&    \
  849.               ( _MPIsFullyInitialized () ) )
  850. /*
  851.    §
  852.    ===========================================================================================
  853.    Miscellaneous Services
  854.    ======================
  855. */
  856.  
  857.  
  858. EXTERN_API_C( void )
  859. _MPLibraryVersion                (const char **            versionCString,
  860.                                  UInt32 *                major,
  861.                                  UInt32 *                minor,
  862.                                  UInt32 *                release,
  863.                                  UInt32 *                revision);
  864.  
  865. /*
  866.    §
  867.    ===========================================================================================
  868.    Unofficial Services
  869.    ===================
  870. */
  871.  
  872.  
  873. /*
  874.    ===========================================================================================
  875.    *** WARNING ***
  876.    These services are not part of the officially documented multiprocessing API.  They may not
  877.    be avaliable in future versions of Mac OS multiprocessing support, or in environments that
  878.    have a different underlying OS architecture such as Mac OS on top of a microkernel, the
  879.    Mac OS Blue Box under Mac OS X, native MP support in Mac OS X, etc.
  880.    ===========================================================================================
  881. */
  882.  
  883. #if CALL_NOT_IN_CARBON
  884. EXTERN_API_C( LogicalAddress )
  885. _MPAllocateSys                    (ByteCount                 size);
  886.  
  887. /* Use MPAllocateAligned instead.*/
  888. EXTERN_API_C( void *)
  889. _MPRPC                            (MPRemoteProcedure         remoteProc,
  890.                                  void *                    parameter);
  891.  
  892. /* Use _MPRemoteCall instead.*/
  893. EXTERN_API_C( Boolean )
  894. _MPTaskIsToolboxSafe            (MPTaskID                 task);
  895.  
  896. #endif  /* CALL_NOT_IN_CARBON */
  897.  
  898. EXTERN_API_C( Boolean )
  899. _MPLibraryIsCompatible            (const char *            versionCString,
  900.                                  UInt32                 major,
  901.                                  UInt32                 minor,
  902.                                  UInt32                 release,
  903.                                  UInt32                 revision);
  904.  
  905.  
  906. #define    MPRPC                    _MPRPC
  907. #define    MPTaskIsToolboxSafe        _MPTaskIsToolboxSafe
  908.  
  909. /*
  910.    §
  911.    ===========================================================================================
  912.    Defunct Services
  913.    ================
  914. */
  915.  
  916. #if CALL_NOT_IN_CARBON
  917. #ifndef MPIncludeDefunctServices
  918. #define MPIncludeDefunctServices 0
  919. #endif  /* !defined(MPIncludeDefunctServices) */
  920.  
  921. #if MPIncludeDefunctServices
  922. EXTERN_API_C( void )
  923. _MPDebugStr                        (ConstStr255Param         msg);
  924.  
  925. EXTERN_API_C( StringPtr )
  926. _MPStatusPString                (OSStatus                 status);
  927.  
  928. EXTERN_API_C( const char *)
  929. _MPStatusCString                (OSStatus                 status);
  930.  
  931.  
  932. #include <stdarg.h>
  933. typedef CALLBACK_API_C( void , MPPrintfHandler )(MPTaskID taskID, const char *format, va_list args);
  934. EXTERN_API_C( void )
  935. _MPInitializePrintf                (MPPrintfHandler         pfn);
  936.  
  937. EXTERN_API_C( void )
  938. _MPPrintf                        (const char *            format,
  939.                                  ...);
  940.  
  941. #endif  /* MPIncludeDefunctServices */
  942.  
  943. #endif  /* CALL_NOT_IN_CARBON */
  944.  
  945. /* ===========================================================================================*/
  946.  
  947.  
  948.  
  949. #if PRAGMA_STRUCT_ALIGN
  950.     #pragma options align=reset
  951. #elif PRAGMA_STRUCT_PACKPUSH
  952.     #pragma pack(pop)
  953. #elif PRAGMA_STRUCT_PACK
  954.     #pragma pack()
  955. #endif
  956.  
  957. #ifdef PRAGMA_IMPORT_OFF
  958. #pragma import off
  959. #elif PRAGMA_IMPORT
  960. #pragma import reset
  961. #endif
  962.  
  963. #ifdef __cplusplus
  964. }
  965. #endif
  966.  
  967. #endif /* __MULTIPROCESSING__ */
  968.  
  969.